home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Tech Arsenal 1
/
Tech Arsenal (Arsenal Computer).ISO
/
tek-04
/
filxrf.zip
/
FILEXREF.DOC
< prev
next >
Wrap
Text File
|
1991-10-01
|
27KB
|
896 lines
FileXref
A New Type of Cross Reference Tool
Version 1.3
October, 1991 Release
ConVal Software, Inc.
_______
____|__ | (R)
--| | |-------------------
| ____|__ | Association of
| | |_| Shareware
|__| o | Professionals
-----| | |---------------------
|___|___| MEMBER
Copyright 1990, 1991 ConVal Software, Inc.
All rights reserved.
ConVal Software, Inc.
11607 E. Butter Creek Road
Moorpark, CA 93021
Sales and
technical support: Monday - Friday
(805) 529-6847 9 AM - 6 PM Pacific Time
Leave a message and I'll contact you the
same or next business day.
7 PM - 10 PM Pacific Time
To speak to me directly.
CompuServe 72330,1621
This program is produced by a member of the Association of
Shareware Professionals (ASP). ASP wants to make sure that the
shareware principle works for you. If you are unable to resolve
a shareware-related problem with an ASP member by contacting the
member directly, ASP may be able to help. The ASP Ombudsman can
help you resolve a dispute or problem with an ASP member, but
does not provide technical support for members' products.
Please write to the ASP Ombudsman at:
ASP Ombudsman
545 Grover Road
Muskegon, MI 49442-9427
U.S.A.
or send a CompuServe message via CompuServe MAIL to ASP Ombudsman
70007,3536.
The ombudsman may be contacted by FAX by sending to the ASP FAX
number: (616) 788-2765. In communication with the ombudsman please
include a telephone number and/or FAX if available.
TABLE OF CONTENTS
INTRODUCTION . . . . . . . . . . . . . . . . . . . . . . . . 4
FEATURES OF FILEXREF . . . . . . . . . . . . . . . . . . . . 5
INSTALLATION . . . . . . . . . . . . . . . . . . . . . . . . 8
SPECIFYING THE FILES TO BE EXAMINED . . . . . . . . . . . . . 9
SPECIFYING WORDS TO SEARCH FOR . . . . . . . . . . . . . . . 10
GETTING STARTED . . . . . . . . . . . . . . . . . . . . . . . 11
NOTES AND RESTRICTIONS . . . . . . . . . . . . . . . . . . . 13
DATA FILE FORMATS . . . . . . . . . . . . . . . . . . . . . . 14
FileXref 1.3 Copyright 1990, 1991 ConVal Software, Inc. Page 3
INTRODUCTION
Having now been a software developer for more years than I care
to admit, I've built a number of support tools for myself. I am
now generalizing and formalizing those tools, making them
available for other developers like you.
FileXref is the first of these and I think you'll find it can
give you a competitive edge for your development projects.
There are three questions that FileXref directly answers.
What is the potential application-wide impact of changing a
particular source file?
When I'm fixing a bug, how can I be sure that I've addressed
the whole class of the underlying problem and not just one
instance?
What components are unused and obsolete?
These questions can't be answered without some groundwork on your
part, however. (Isn't that always the case?)
FileXref needs access to text file representations of ALL
components of your application. This includes your source code as
well as documentation files, program specs, etc. It also needs
your files to follow minimum naming conventions. For example file
extensions must indicate the type of data held in the file. So .C
files imply C source code, while .BAT files imply batch files,
and .TXT or .DOC implies a printable text file.
Although it is not a requirement for FileXref, you will reduce
your own analysis problems if you :
never let variable names match any of your filenames,
make your filenames unique across all the file types you
use, and
group related files in a minimum of subdirectories.
Running the demonstration provided will give you a series of
reports to assist you in being able to answer the three questions
above for the application you are developing or maintaining. (See
the README.DOC file for instructions for running the DEMO.)
FileXref 1.3 Copyright 1990, 1991 ConVal Software, Inc. Page 4
FEATURES OF FILEXREF
FileXref analyzes a list of text files, extracting cross
reference information which it stores in memory. It can process
all text files and this version has special processing locic for
supporting the syntax of the following file types:
FILE
EXTENSION CATEGORY
---- --------------------
.BAS BASIC
.BAT Batch Files
.C .H C source
.CPP .HPP C++ source
.COB COBOL
.FOR FORTRAN
.ASM Macro Assembler
.MAK Make files
.PAS Pascal
.PLI PL/I
.REX REXX
.SQL .INP Oracle
.TXT Text (ASCII)
.DOC Text (ASCII)
.PRG xBASE
All other types are scanned as if they were ASCII text files
with no regard to whether a reference was found in a
"comment".
You will prepare the list of files to be examined and insure that
it represents all files related to your application. Or, you may
use a utility, FileList (see Page 9), to create a list of all
files on a disk drive which match one of the file types currently
supported by FileXref.
You'll optionally prepare a list of words and/or word prefixes
you'd like cross referenced.
Note that if you have a very large disk with much more
source code than your application, this may cause FileXref
to run "out of memory". If this happens, use your text
editor to pare down the list generated by FileList to just
those files needed by your application. You may also need to
reduce the list of words and word prefixes you supplied.
The FileXref utility will generate report files containing cross
reference information for the list of files and words provided.
FileXref 1.3 Copyright 1990, 1991 ConVal Software, Inc. Page 5
Three report files may be produced:
A List of Unreferenced Files,
A File Usage Report, and
A Word Usage Report.
The List of Unreferenced Files lists every file which was
referenced by no other file examined. So this list contains your
application's top level components. You would expect to see top
level overview specs and/or batch files in this list.
It also will contain components not yet documented.
This will assist you in keeping documentation up to date
with the product.
And it may contain obsolete components.
Now you have a tool to keep obsolete components from
confusing the development and maintenance effort!
The File Usage Report shows, for every file examined, each file
which references it. This report may be selected in two styles. A
condensed version is available for applications with source code
localized to a small number of subdirectories. An extended style
is available for others.
This report will tell you the global impact of changing a file.
By examining the list of impacted files repeatedly, you can
construct a completely exploded tree representing the "ripple
effect" of changing the one file.
The Word Usage Report is optional. If you supply a list of words
or word prefixes to FileXref, it will cross reference the words
and word prefixes to the files referencing them. This report also
is available in condensed and extended styles.
By following the following conventions the Word Usage Report can
be a valuable aid to problem solving.
o use meaningful names for variables
o use the same name for the same variable in all modules
o don't use variable names which are the same as keywords in any
of the languages you're using
The Word Usage Report will show everywhere in your application
each variable (word) is used.
FileXref 1.3 Copyright 1990, 1991 ConVal Software, Inc. Page 6
So if you are working a bug having to do with the value of a
counter, the report will show you every reference to the counter
variable in the system - including documentation and support
files! You will be able to address the counter's integrity
throughout the system instead of just in the particular instance
where it was incorrectly set. Here then is a tool for solving
problems, not just addressing individual symptoms!
As an alternative to producing report files, FileXref can instead
generate cross reference data files. These files are in a "quote
and comma delimited" format. You may load these files into your
spreadsheet or database program and work with the data that way.
FileXref 1.3 Copyright 1990, 1991 ConVal Software, Inc. Page 7
INSTALLATION
FileXref requires an IBM PC, XT, AT, PS/2 or compatible computer
with 256K of RAM. Your CONFIG.SYS file must specify FILES=10 or more
for the program to run. In addition, version 2.0 or greater of
PC-DOS or MS-DOS is required.
FileXref requires approximately 100K of computer memory to
contain the program's executable code. Additional memory is
allocated as required to contain the list of files and words
being processed and cross reference information about them. This
data is allocated in conventional memory. FileXref will acquire
as much conventional memory as is available to handle large
applications and/or large numbers of words to be cross
referenced.
FileXref is not a Terminate and Stay Resident program, so the
memory it uses is only required when you are actually running the
program.
Installing FileXref is very simple. There is only one file
required to run the program. This is FILEXREF.EXE (the program
itself). Copy this file to one of the directories identified in
your PATH command.
In order to run the DEMO, copy three additional files -
FILELIST.EXE (a support utility), FILEXREF.WSL (an input file for
the DEMO), and DEMO.BAT (a batch file to run the DEMO).
When FileXref is started with no command-line arguments, it
assumes its input control files (FSL and WSL) are in the current
directory and it creates its output files (RPT, XRF, FEI and MSG)
in the current directory.
For other options, see page 11.
FileXref 1.3 Copyright 1990, 1991 ConVal Software, Inc. Page 8
SPECIFYING THE FILES TO BE EXAMINED
A File Specification List (FSL) file identifies to FileXref the
files to be scanned and cross referenced. It is a text file which
may be created with any text editor. Each file spec must start in
column one of the record and only one file spec may exist on each
record.
Example:
C:\SOURCE\MAINPGM.C
C:\SOURCE\SUBPGM1.C
C:\SOURCE\SUBPGM2.C
C:\SOURCE\INCLUDE\INFILE.H
C:\SOURCE\INCLUDE\OUTFILE.H
A:\SAMPLES\DEMO01.TXT
By naming all files in your application for FileXref, you insure
that you will get a complete cross referencing.
To ease the effort in preparing this file, a utility called
FileList is provided for you. Given a starting directory, it
will READ all files in that directory, writing each filename
matching a file type that FileXref knows how to scan. It
recursively processes subdirectories so that all files in the
tree starting with the specified directory are extracted. It
produces its output to the DOS standard output, so it can be
redirected.
Example 1: This causes FileList to create an input file for
FileXref of all files on C:\SOURCE and its
subdirectories.
FILELIST C:\SOURCE > FILEXREF.FSL
Example 2: This causes FileList to create an input file for
FileXref of all files on the C disk.
FILELIST C: > FILEXREF.FSL
Example 3: This causes FileList to create an input file for
FileXref of all files on the C, D, and E disks.
FILELIST C: > FILEXREF.FSL
FILELIST D: >> FILEXREF.FSL
FILELIST E: >> FILEXREF.FSL
FileXref 1.3 Copyright 1990, 1991 ConVal Software, Inc. Page 9
SPECIFYING WORDS TO SEARCH FOR
An optional input to FileXref is a Word Specification List (WSL)
file. This contains words and word prefixes you wish to see cross
referenced to the files that reference them as well as those to
be excluded from the resulting list (for example language keywords).
Use a text editor to create this file. Start each entry in column
one and place a code and a word or word prefix on each record. The
code must be "I" for Include or "X" for eXclude. Terminate word
prefixes with an "*". All entries will be raised to upper case by
FileXref when output.
Example 01: Cross reference all uses of the whole word "malloc",
the whole word "extern" all symbols that start
with the letters "str", and exclude the words
"if" and "else".
I malloc
I extern
I str*
X if
X else
Example 02: Cross reference all symbols
I *
NOTE: This option will use up memory very quickly, since ALL
words will be cross referenced (even words like "the",
"and", "a"). If you use this option you may need to limit
the number of files to examine, or use the technique in the
next example.
Example 03: Cross reference a portion of the alphabet on
one pass of the files. Use multiple passes to cover
the whole alphabet. Use this technique if you get an
"out of memory" type of error message.
I A*
I B*
I C*
I D*
I E*
I F*
.
.
.
FileXref 1.3 Copyright 1990, 1991 ConVal Software, Inc. Page 10
GETTING STARTED
Prior to running FileXref, create the list of files to be
examined (see page 9) and, optionally, the list of words and word
prefixes to be cross referenced (see page 10). Remember that the
program won't run unless CONFIG.SYS contains FILES=10.
The usual way to start up FileXref is to type FileXref and press
Enter at the DOS prompt. However, the following parameters can be
specified on the command line to modify FileXref's behavior
during a particular run. The general command line syntax for
running FileXref is:
FILEXREF [opt fsl xrf fei msg wsl rpt]
where opt is: ? Causes FileXref to display help
information.
/RPTS Instructs FileXref to create only
extended reports.
/RPTC Tells FileXref to create only
condensed reports. (This is the
default.)
/RPTB Directs FileXref to create both
extended and condensed reports (the DEMO
uses this).
/RPTN Specifies that no reports are to be
generated - produce data files instead.
fsl is a file specification for the input file containing
file specifications for each source to be
examined. If omitted, this defaults to
FILEXREF.FSL.
xrf is a file specification for the output cross
reference data file. If omitted, this defaults to
FILEXREF.XRF.
fei is a file specification for the output data file to
contain a list of unreferenced files. If omitted,
this defaults to FILEXREF.FEI.
msg is a file specification for the output file of
run statistics. If omitted, this defaults to
FILEXREF.MSG.
wsl is an optional file specification for the input file
containing the words and word prefixes to be cross
referenced. If omitted, this defaults to
FILEXREF.WSL.
rpt is an optional file specification for the output file
containing the reports. If omitted, FILEXREF.RPT.
FileXref 1.3 Copyright 1990, 1991 ConVal Software, Inc. Page 11
Example 1: Take all the defaults.
FILEXREF
The two control files (FSL and WSL) must be in the current
directory. This will read file specifications from
FILEXREF.FSL and will look for optional word specifications
in FILEXREF.WSL. Messages will be output to FILEXREF.MSG.
Since the default processing is /RPTC, condensed reports
will be written to FILEXREF.RPT, while files FILEXREF.XRF
and FILEXREF.FEI will be empty.
Example 2: Create data files instead of report files.
FILEXREF /RPTN
This invocation will cause cross reference data (in quote
and comma delimited format) to be written to FILEXREF.XRF
and unreferenced symbols to be written to FILEXREF.FEI. No
report file will be generated.
Example 3: Override the location and naming of the report file.
FILEXREF /RPTC FILEXREF.FSL FILEXREF.XRF
FILEXREF.FEI FILEXREF.MSG FILEXREF.WSL
C:\DATA\MYREPORT.FIL
NOTE: Although the above is shown as three separate lines,
you would type it all in at the DOS prompt and press enter
once.
NOTE: All pameters are positional. So, to override the last
one, we supplied the defaults for all others. That is, none
may be omitted prior to the one you wish to override.
FileXref 1.3 Copyright 1990, 1991 ConVal Software, Inc. Page 12
NOTES AND RESTRICTIONS
1. The FileXref utility distinguishes the comment syntax of
each file extension, i.e. REM in .BAT files and /* */ in
C files. Symbols found within comments are not cross
referenced.
2. Symbols found in quotes or apostrophes are cross referenced.
3. If you get the message "Insufficient memory", try reducing
the scope of the processing. This may mean limiting the file
specification list (FSL) entries to only those files used by
your application and/or eliminating / limiting the word
specification list (WSL) entries to just those you need to
see. Or see example 3 on page 10 for a multiple pass
solution.
4. Only the first 31 chacters of a symbol are retained.
5. Symbols are all converted to upper-case in the report and
data files.
6. Cross reference entries will be created only for filenames
and symbols that are consistent with the symbol naming
convention for each source file type.
So the restriction means that if the following is a fragment
from a .C file, a cross reference entry would not be created
for lines 3 or 4 below, even though these are valid DOS file
names. This is because the names are not valid C symbols.
1. avg_value = get_avg ( list ); OK
2. fp = fopen ( "C:\\TEST.dat", "r" ); OK
3. fp = fopen ( "87tax.dat", "w" ); starts with
a digit
4. strcpy ( fspec, "A:$budget.trn" ); starts with $
FileXref 1.3 Copyright 1990, 1991 ConVal Software, Inc. Page 13
DATA FILE FORMATS
FILEXREF.XRF Columns are quote and comma delimited.
====> FILENAME2 IS REFERENCED BY FILENAME1
COLUMN COLUMN COLUMN
1 2 3
------------------------------------
FILENAME2 FILENAME1 F
====> WORD MATCHING A WORD PREFIX IS REFERENCED BY
FILENAME1
NOTE: THE WHOLE WORD, NOT JUST THE PREFIX IS IN
COLUMN ONE.
COLUMN COLUMN COLUMN
1 2 3
------------------------------------
WORD FILENAME1 E
====> WORD IS REFERENCED BY FILENAME1
COLUMN COLUMN COLUMN
1 2 3
------------------------------------
WORD FILENAME1 W
====> WORD PREFIX IS REFERENCED BY FILENAME1
COLUMN COLUMN COLUMN
1 2 3
------------------------------------
WORD FILENAME1 P
FileXref 1.3 Copyright 1990, 1991 ConVal Software, Inc. Page 14
FILEXREF.FEI Columns are quote and comma delimited.
====> UNREFERENCED FILENAME:
COLUMN COLUMN
1 2
------------------------
FILENAME F
====> UNREFERENCED WORD PREFIX:
COLUMN COLUMN
1 2
------------------------
WORD PREFIX P
====> UNREFERENCED WORD:
COLUMN COLUMN
1 2
------------------------
WORD W
FileXref 1.3 Copyright 1990, 1991 ConVal Software, Inc. Page 15
End of FileXref Documentation.